docs: point Claude Code MCP setup at the file Claude Code reads - #25

i am an AI agent (Claude) working on behalf of Anton Dzyatkovsky, who reviews what i open.

What was broken

README.md (Layer 3: MCP Server) and the mcp_server.py docstring both tell Claude Code
users to put the mcpServers block in ~/.claude/claude_desktop_config.json.

Claude Code does not read that file. claude_desktop_config.json belongs to Claude Desktop,
a separate product that keeps it in its own application-support directory, not under
~/.claude/. A reader who follows the README gets no server and no error: the block lands in
a file nothing reads.

How i checked

Claude Code 2.1.202 on macOS. Same JSON in both runs, only the location differs.

1. The location the README names. Wrote the exact block from the README (with a real
command: a venv python plus this repo's mcp_server.py) to ~/.claude/claude_desktop_config.json,
with no .mcp.json in the working directory:

$ claude mcp list
telegram: ... - OK Connected
agent-chrome: ... - OK Connected

Two pre-existing user-scope servers answer; x-reader never appears. Count of x-reader lines: 0.

2. Same JSON, in the file Claude Code reads. claude mcp add x-reader -- <venv-python> mcp_server.py
writes .mcp.json in the project:

$ claude mcp list
x-reader: <venv-python> .../mcp_server.py - OK Connected

That is a real handshake, not a file check: python 3.12 venv, pip install -e ".[mcp]", and the
server answered.

I also checked that the hand-written form kept in the README works as written: claude mcp add
adds a "type": "stdio" key, and Claude Code still recognises the block without it.

What the docs say now

• claude mcp add ... as the primary instruction, with a note that it writes .mcp.json in the
  project and that --scope user writes ~/.claude.json instead.
• The same hand-written JSON block kept, now labelled as .mcp.json.
• One sentence saying Claude Desktop is a separate product with its own
  claude_desktop_config.json, so the next reader does not re-derive the wrong path.
• The identical correction in the mcp_server.py docstring, so the two copies do not drift apart.

No code paths touched. The repo's own CI command on the patched tree:

$ python -m unittest discover -s tests -p "test_*.py"
Ran 10 tests in 0.460s
OK